/**
 * @file protocol_sequence.c
 * @brief 104协议序列号管理实现
 * @details 本文件实现了104协议的序列号管理功能，包括发送序列号、接收序列号
 *          管理、序列号验证、序列号回绕处理等。实现完整的104协议序列号控制逻辑。
 * 
 *          主要功能包括：
 *          - 序列号生成：管理发送序列号的生成和递增
 *          - 序列号验证：验证接收序列号的有效性
 *          - 序列号确认：处理发送和接收序列号的确认
 *          - 窗口管理：管理接收窗口和未确认序列号
 *          - 重复检测：检测和处理重复序列号
 *          - 乱序处理：处理乱序到达的序列号
 *          - 回绕处理：处理序列号回绕情况
 *          - 统计信息：记录序列号相关的统计数据
 *          - 回调机制：支持错误和回绕事件通知
 * 
 * @author zyb
 * @date 2025-10-15
 * @version 1.0
 * 
 * @note 本模块是104协议栈的核心组件，负责管理协议序列号的生命周期
 * @warning 所有函数都是线程安全的，使用互斥锁保护共享数据
 * @see protocol_sequence.h
 * @see protocol_types.h
 * @see constants.h
 */

#include "../include/protocol_sequence.h"
#include "../../common/types/include/constants.h"
#include "../../../../../common/logs/include/logger.h"
#include <stdlib.h>
#include <string.h>
#include <pthread.h>

// 定义模块名称
#define LOG_MODULE_NAME "PROTOCOL_SEQUENCE"

/* ==================== 序列号管理器私有数据结构 ==================== */

/**
 * @brief 序列号管理器私有数据结构
 * @details 该结构体包含了序列号管理器的所有私有数据，包括配置信息、
 *          统计信息、序列号状态、窗口管理、回调函数和线程安全控制等。
 *          所有数据都通过互斥锁进行线程安全保护。
 */
typedef struct {
    /* ==================== 配置和统计 ==================== */
    protocol_sequence_config_t config; /* 序列号配置参数，包括最大序列号、窗口大小等 */
    protocol_sequence_stats_t stats;   /* 序列号统计信息，记录各种操作次数和状态 */
    
    /* ==================== 序列号状态管理 ==================== */
    uint16_t current_send_seq;         /* 当前发送序列号：下一个要发送的序列号 */
    uint16_t current_receive_seq;      /* 当前接收序列号：已确认接收的最大序列号 */
    uint16_t expected_receive_seq;     /* 期望接收序列号：下一个期望接收的序列号 */
    
    /* ==================== 未确认序列号管理 ==================== */
    uint16_t unacknowledged_send[16];  /* 未确认的发送序列号数组：记录已发送但未确认的序列号 */
    uint16_t unacknowledged_count;     /* 未确认数量：当前未确认的序列号个数 */
    
    /* ==================== 接收窗口管理 ==================== */
    bool received_window[16];          /* 接收窗口数组：记录窗口内序列号的接收状态 */
    uint16_t window_start;             /* 窗口起始位置：接收窗口的起始序列号 */
    
    /* ==================== 回调函数管理 ==================== */
    protocol_sequence_error_callback_t error_callback;  /* 序列号错误回调函数指针 */
    void* error_user_data;                             /* 错误回调用户数据指针 */
    protocol_sequence_wrap_callback_t wrap_callback;    /* 序列号回绕回调函数指针 */
    void* wrap_user_data;                              /* 回绕回调用户数据指针 */
    
    /* ==================== 线程安全控制 ==================== */
    pthread_mutex_t mutex;             /* 互斥锁：保护共享数据的线程安全 */
} protocol_sequence_private_t;

/* ==================== 序列号管理函数实现 ==================== */

/**
 * @brief 创建序列号管理器
 * @details 创建并初始化一个新的104协议序列号管理器实例。该函数会分配内存、
 *          验证配置参数、初始化内部状态和互斥锁，并设置初始的序列号状态。
 *          序列号管理器负责处理发送序列号生成、接收序列号验证、窗口管理等功能。
 * 
 * @param config 序列号配置参数指针，不能为NULL
 * 
 * @return 序列号管理器句柄，成功返回有效句柄，失败返回NULL
 * 
 * @note 创建的序列号管理器需要调用protocol_sequence_destroy()释放资源
 * @warning 配置参数必须通过protocol_sequence_validate_config()验证
 * @see protocol_sequence_destroy
 * @see protocol_sequence_validate_config
 */
protocol_sequence_handle_t protocol_sequence_create(const protocol_sequence_config_t* config) {
    LOG_DEBUG(LOG_MODULE_NAME, "开始创建序列号管理器");
    
    if (config == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "配置参数为空指针");
        return NULL;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "验证序列号配置参数，最大序列号: %u, 窗口大小: %u", 
             config->max_sequence_number, config->window_size);
    
    // 验证配置
    if (protocol_sequence_validate_config(config) != PROTOCOL_SUCCESS) {
        LOG_ERROR(LOG_MODULE_NAME, "序列号配置参数验证失败");
        return NULL;
    }
    
    LOG_DEBUG(LOG_MODULE_NAME, "分配序列号管理器内存");
    protocol_sequence_private_t* private_data = 
        (protocol_sequence_private_t*)malloc(sizeof(protocol_sequence_private_t));
    if (private_data == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "内存分配失败");
        return NULL;
    }
    
    LOG_DEBUG(LOG_MODULE_NAME, "初始化序列号管理器私有数据");
    memset(private_data, 0, sizeof(protocol_sequence_private_t));
    
    // 复制配置
    memcpy(&private_data->config, config, sizeof(protocol_sequence_config_t));
    
    // 初始化序列号
    private_data->current_send_seq = 0;
    private_data->current_receive_seq = 0;
    private_data->expected_receive_seq = 0;
    private_data->unacknowledged_count = 0;
    private_data->window_start = 0;
    
    LOG_INFO(LOG_MODULE_NAME, "初始化序列号状态，发送序列号: %u, 接收序列号: %u", 
             private_data->current_send_seq, private_data->current_receive_seq);
    
    // 初始化互斥锁
    LOG_DEBUG(LOG_MODULE_NAME, "初始化互斥锁");
    if (pthread_mutex_init(&private_data->mutex, NULL) != 0) {
        LOG_ERROR(LOG_MODULE_NAME, "互斥锁初始化失败");
        free(private_data);
        return NULL;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "序列号管理器创建成功");
    return (protocol_sequence_handle_t)private_data;
}

/**
 * @brief 销毁序列号管理器
 * @details 销毁序列号管理器实例，清理所有相关资源。该函数会先销毁互斥锁，
 *          然后释放内存。这是protocol_sequence_create()的配对函数，用于释放
 *          序列号管理器占用的所有资源。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 销毁成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 * 
 * @note 调用此函数后，序列号管理器句柄将变为无效，不应再使用
 * @warning 此函数会清理所有序列号状态，请确保在合适的时机调用
 * @see protocol_sequence_create
 */
protocol_error_t protocol_sequence_destroy(protocol_sequence_handle_t handle) {
    LOG_DEBUG(LOG_MODULE_NAME, "开始销毁序列号管理器");
    
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "序列号管理器句柄为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_sequence_private_t* private_data = (protocol_sequence_private_t*)handle;
    
    LOG_INFO(LOG_MODULE_NAME, "销毁序列号管理器，当前发送序列号: %u, 接收序列号: %u", 
             private_data->current_send_seq, private_data->current_receive_seq);
    
    // 销毁互斥锁
    LOG_DEBUG(LOG_MODULE_NAME, "销毁互斥锁");
    pthread_mutex_destroy(&private_data->mutex);
    
    // 释放内存
    LOG_DEBUG(LOG_MODULE_NAME, "释放序列号管理器内存");
    free(private_data);
    
    LOG_INFO(LOG_MODULE_NAME, "序列号管理器销毁成功");
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 获取下一个发送序列号
 * @details 获取下一个可用的发送序列号。该函数会检查未确认序列号数量是否超过限制，
 *          如果未超过限制，则分配下一个序列号并添加到未确认列表中。如果序列号
 *          超过最大值，会自动进行回绕处理。该函数是线程安全的，使用互斥锁保护。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param sequence_number 序列号输出缓冲区，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 获取成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 参数为空指针
 *         - PROTOCOL_ERROR_BUFFER_OVERFLOW: 序列号窗口已满
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 序列号会自动递增，超过最大值时会回绕到0
 * @warning 如果未确认序列号数量达到最大值，将无法获取新的序列号
 * @see protocol_sequence_acknowledge_send
 * @see protocol_sequence_can_send
 */
protocol_error_t protocol_sequence_get_next_send(protocol_sequence_handle_t handle, 
                                                uint16_t* sequence_number) {
    LOG_DEBUG(LOG_MODULE_NAME, "开始获取下一个发送序列号，句柄: %p, 输出指针: %p", handle, sequence_number);
    
    if (handle == NULL || sequence_number == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "参数为空指针，句柄: %p, 序列号输出: %p", handle, sequence_number);
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_sequence_private_t* private_data = (protocol_sequence_private_t*)handle;
    
    LOG_DEBUG(LOG_MODULE_NAME, "获取互斥锁");
    pthread_mutex_lock(&private_data->mutex);
    
    // 检查是否可以发送
    LOG_DEBUG(LOG_MODULE_NAME, "检查未确认序列号数量: %u >= %u", 
              private_data->unacknowledged_count, private_data->config.max_unacknowledged);
    if (private_data->unacknowledged_count >= private_data->config.max_unacknowledged) {
        LOG_ERROR(LOG_MODULE_NAME, "序列号窗口已满，未确认数量: %u", private_data->unacknowledged_count);
        pthread_mutex_unlock(&private_data->mutex);
        return PROTOCOL_ERROR_BUFFER_OVERFLOW;
    }
    
    // 获取下一个序列号
    *sequence_number = private_data->current_send_seq;
    LOG_INFO(LOG_MODULE_NAME, "分配发送序列号: %u", *sequence_number);
    
    // 添加到未确认列表
    private_data->unacknowledged_send[private_data->unacknowledged_count] = *sequence_number;
    private_data->unacknowledged_count++;
    LOG_DEBUG(LOG_MODULE_NAME, "添加到未确认列表，位置: %u, 未确认数量: %u", 
              private_data->unacknowledged_count - 1, private_data->unacknowledged_count);
    
    // 更新发送序列号
    uint16_t old_seq = private_data->current_send_seq;
    private_data->current_send_seq++;
    LOG_DEBUG(LOG_MODULE_NAME, "更新发送序列号: %u -> %u", old_seq, private_data->current_send_seq);
    
    if (private_data->current_send_seq > private_data->config.max_sequence_number) {
        // 序列号回绕
        LOG_WARN(LOG_MODULE_NAME, "序列号回绕: %u -> 0", private_data->current_send_seq);
        private_data->current_send_seq = 0;
        private_data->stats.sequence_wraps++;
        LOG_DEBUG(LOG_MODULE_NAME, "序列号回绕计数: %u", private_data->stats.sequence_wraps);
        
        // 调用回绕回调
        if (private_data->wrap_callback) {
            LOG_DEBUG(LOG_MODULE_NAME, "调用序列号回绕回调函数");
            private_data->wrap_callback(SEQUENCE_DIRECTION_SEND, old_seq, 0, private_data->wrap_user_data);
        }
    }
    
    // 更新统计信息
    private_data->stats.total_sent++;
    private_data->stats.current_send_seq = private_data->current_send_seq;
    LOG_DEBUG(LOG_MODULE_NAME, "更新发送统计: 总发送数=%u, 当前发送序列号=%u", 
              private_data->stats.total_sent, private_data->stats.current_send_seq);
    
    pthread_mutex_unlock(&private_data->mutex);
    LOG_DEBUG(LOG_MODULE_NAME, "释放互斥锁");
    
    LOG_INFO(LOG_MODULE_NAME, "成功获取发送序列号: %u", *sequence_number);
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 验证接收序列号
 * @details 验证接收到的序列号是否有效。该函数会检查序列号是否在有效范围内、
 *          是否在接收窗口内、是否为重复序列号等。验证结果用于决定是否接受
 *          该序列号的数据。该函数是线程安全的，使用互斥锁保护。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param sequence_number 要验证的序列号
 * 
 * @return 序列号状态
 *         - SEQUENCE_STATE_VALID: 序列号有效
 *         - SEQUENCE_STATE_INVALID: 序列号无效（超出范围）
 *         - SEQUENCE_STATE_OUT_OF_ORDER: 序列号乱序（不在窗口内）
 *         - SEQUENCE_STATE_DUPLICATE: 序列号重复
 *         - SEQUENCE_STATE_OVERFLOW: 序列号溢出
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 验证结果会影响统计信息的更新
 * @warning 如果句柄为NULL，返回SEQUENCE_STATE_INVALID
 * @see protocol_sequence_acknowledge_receive
 * @see protocol_sequence_is_in_window
 */
sequence_state_t protocol_sequence_validate_receive(protocol_sequence_handle_t handle, 
                                                   uint16_t sequence_number) {
    LOG_DEBUG(LOG_MODULE_NAME, "开始验证接收序列号，句柄: %p, 序列号: %u", handle, sequence_number);
    
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "序列号管理器句柄为空指针");
        return SEQUENCE_STATE_INVALID;
    }
    
    protocol_sequence_private_t* private_data = (protocol_sequence_private_t*)handle;
    
    LOG_DEBUG(LOG_MODULE_NAME, "获取互斥锁");
    pthread_mutex_lock(&private_data->mutex);
    
    sequence_state_t state = SEQUENCE_STATE_VALID;
    
    // 检查序列号是否在有效范围内
    if (sequence_number > private_data->config.max_sequence_number) {
        state = SEQUENCE_STATE_INVALID;
        private_data->stats.invalid_sequences++;
        LOG_WARN(LOG_MODULE_NAME, "序列号超出有效范围: %u > %u", 
                    sequence_number, private_data->config.max_sequence_number);
    }
    // 检查是否在接收窗口内
    else if (!protocol_sequence_is_in_window(sequence_number, private_data->window_start, 
                                           private_data->config.window_size, 
                                           private_data->config.max_sequence_number)) {
        state = SEQUENCE_STATE_OUT_OF_ORDER;
        private_data->stats.out_of_order_detected++;
        LOG_WARN(LOG_MODULE_NAME, "序列号乱序，不在接收窗口内: %u, 窗口起始: %u, 窗口大小: %u", 
                    sequence_number, private_data->window_start, private_data->config.window_size);
    }
    // 检查是否重复
    else if (private_data->config.enable_duplicate_detection) {
        uint16_t window_index = (sequence_number - private_data->window_start) % private_data->config.window_size;
        if (private_data->received_window[window_index]) {
            state = SEQUENCE_STATE_DUPLICATE;
            private_data->stats.duplicates_detected++;
            LOG_WARN(LOG_MODULE_NAME, "检测到重复序列号: %u, 窗口索引: %u", 
                        sequence_number, window_index);
        }
    }
    
    LOG_INFO(LOG_MODULE_NAME, "序列号验证完成，序列号: %u, 状态: %s", 
             sequence_number, protocol_sequence_get_state_name(state));
    
    pthread_mutex_unlock(&private_data->mutex);
    LOG_DEBUG(LOG_MODULE_NAME, "释放互斥锁");
    
    return state;
}

/**
 * @brief 确认接收序列号
 * @details 确认接收到的序列号，更新接收状态和窗口管理。该函数会验证序列号的有效性，
 *          标记序列号为已接收，更新期望接收序列号，并移动接收窗口。如果序列号是连续的，
 *          会自动更新窗口位置。该函数是线程安全的，使用互斥锁保护。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param sequence_number 要确认的序列号
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 确认成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 *         - PROTOCOL_ERROR_INVALID_PARAM: 序列号无效
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 只有有效的序列号才能被确认
 * @warning 确认序列号会影响接收窗口的位置
 * @see protocol_sequence_validate_receive
 * @see protocol_sequence_get_current_receive
 */
protocol_error_t protocol_sequence_acknowledge_receive(protocol_sequence_handle_t handle, 
                                                      uint16_t sequence_number) {
    LOG_DEBUG(LOG_MODULE_NAME, "开始确认接收序列号，句柄: %p, 序列号: %u", handle, sequence_number);
    
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "序列号管理器句柄为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_sequence_private_t* private_data = (protocol_sequence_private_t*)handle;
    
    LOG_DEBUG(LOG_MODULE_NAME, "获取互斥锁");
    pthread_mutex_lock(&private_data->mutex);
    
    // 验证序列号
    sequence_state_t state = protocol_sequence_validate_receive(handle, sequence_number);
    if (state != SEQUENCE_STATE_VALID) {
        LOG_ERROR(LOG_MODULE_NAME, "序列号验证失败，序列号: %u, 状态: %s", 
                  sequence_number, protocol_sequence_get_state_name(state));
        pthread_mutex_unlock(&private_data->mutex);
        return PROTOCOL_ERROR_INVALID_PARAM;
    }
    
    // 标记为已接收
    uint16_t window_index = (sequence_number - private_data->window_start) % private_data->config.window_size;
    private_data->received_window[window_index] = true;
    LOG_DEBUG(LOG_MODULE_NAME, "标记序列号为已接收，序列号: %u, 窗口索引: %u", 
              sequence_number, window_index);
    
    // 更新接收序列号
    if (sequence_number == private_data->expected_receive_seq) {
        LOG_DEBUG(LOG_MODULE_NAME, "连续接收序列号，更新期望接收序列号");
        // 连续接收，更新期望序列号
        do {
            private_data->expected_receive_seq++;
            if (private_data->expected_receive_seq > private_data->config.max_sequence_number) {
                private_data->expected_receive_seq = 0;
            }
            
            // 检查下一个位置是否已接收
            uint16_t next_index = (private_data->expected_receive_seq - private_data->window_start) % private_data->config.window_size;
            if (!private_data->received_window[next_index]) {
                break;
            }
        } while (true);
        
        // 移动接收窗口
        while (private_data->window_start != private_data->expected_receive_seq) {
            uint16_t old_index = private_data->window_start % private_data->config.window_size;
            private_data->received_window[old_index] = false;
            private_data->window_start++;
            if (private_data->window_start > private_data->config.max_sequence_number) {
                private_data->window_start = 0;
            }
        }
        LOG_DEBUG(LOG_MODULE_NAME, "移动接收窗口，新窗口起始: %u, 期望接收序列号: %u", 
                  private_data->window_start, private_data->expected_receive_seq);
    }
    
    // 更新统计信息
    private_data->stats.total_received++;
    private_data->stats.current_receive_seq = private_data->current_receive_seq;
    LOG_DEBUG(LOG_MODULE_NAME, "更新接收统计: 总接收数=%u, 当前接收序列号=%u", 
              private_data->stats.total_received, private_data->stats.current_receive_seq);
    
    pthread_mutex_unlock(&private_data->mutex);
    LOG_DEBUG(LOG_MODULE_NAME, "释放互斥锁");
    
    LOG_INFO(LOG_MODULE_NAME, "成功确认接收序列号: %u", sequence_number);
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 确认发送序列号
 * @details 确认发送的序列号已被接收，更新发送状态。该函数会从未确认列表中
 *          查找并移除指定的序列号，表示该序列号的数据已被对方确认接收。
 *          该函数是线程安全的，使用互斥锁保护。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param sequence_number 要确认的序列号
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 确认成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 *         - PROTOCOL_ERROR_INVALID_PARAM: 序列号未找到
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 只有未确认列表中的序列号才能被确认
 * @warning 确认序列号会减少未确认数量，可能允许发送新的序列号
 * @see protocol_sequence_get_next_send
 * @see protocol_sequence_get_unacknowledged_count
 */
protocol_error_t protocol_sequence_acknowledge_send(protocol_sequence_handle_t handle, 
                                                   uint16_t sequence_number) {
    LOG_DEBUG(LOG_MODULE_NAME, "开始确认发送序列号，句柄: %p, 序列号: %u", handle, sequence_number);
    
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "序列号管理器句柄为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_sequence_private_t* private_data = (protocol_sequence_private_t*)handle;
    
    LOG_DEBUG(LOG_MODULE_NAME, "获取互斥锁");
    pthread_mutex_lock(&private_data->mutex);
    
    // 查找并移除未确认的序列号
    bool found = false;
    LOG_DEBUG(LOG_MODULE_NAME, "在未确认列表中查找序列号: %u, 未确认数量: %u", 
              sequence_number, private_data->unacknowledged_count);
    
    for (uint16_t i = 0; i < private_data->unacknowledged_count; i++) {
        if (private_data->unacknowledged_send[i] == sequence_number) {
            // 移除这个序列号
            for (uint16_t j = i; j < private_data->unacknowledged_count - 1; j++) {
                private_data->unacknowledged_send[j] = private_data->unacknowledged_send[j + 1];
            }
            private_data->unacknowledged_count--;
            found = true;
            LOG_DEBUG(LOG_MODULE_NAME, "找到并移除序列号: %u, 位置: %u, 剩余未确认数量: %u", 
                      sequence_number, i, private_data->unacknowledged_count);
            break;
        }
    }
    
    pthread_mutex_unlock(&private_data->mutex);
    LOG_DEBUG(LOG_MODULE_NAME, "释放互斥锁");
    
    if (!found) {
        LOG_ERROR(LOG_MODULE_NAME, "未找到要确认的序列号: %u", sequence_number);
        return PROTOCOL_ERROR_INVALID_PARAM;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "成功确认发送序列号: %u", sequence_number);
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 重置序列号管理器
 * @details 重置序列号管理器到初始状态，清空所有序列号状态和窗口信息。
 *          该函数会将发送序列号、接收序列号、未确认列表、接收窗口等
 *          所有状态重置为初始值。该函数是线程安全的，使用互斥锁保护。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 重置成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 重置后所有序列号状态都将回到初始状态
 * @warning 重置操作不可逆，请谨慎使用
 * @see protocol_sequence_create
 * @see protocol_sequence_get_current_send
 * @see protocol_sequence_get_current_receive
 */
protocol_error_t protocol_sequence_reset(protocol_sequence_handle_t handle) {
    LOG_DEBUG(LOG_MODULE_NAME, "开始重置序列号管理器，句柄: %p", handle);
    
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "序列号管理器句柄为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_sequence_private_t* private_data = (protocol_sequence_private_t*)handle;
    
    LOG_DEBUG(LOG_MODULE_NAME, "获取互斥锁");
    pthread_mutex_lock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "重置序列号状态，当前发送序列号: %u -> 0, 接收序列号: %u -> 0", 
             private_data->current_send_seq, private_data->current_receive_seq);
    
    // 重置所有序列号
    private_data->current_send_seq = 0;
    private_data->current_receive_seq = 0;
    private_data->expected_receive_seq = 0;
    private_data->unacknowledged_count = 0;
    private_data->window_start = 0;
    
    // 清空接收窗口
    memset(private_data->received_window, 0, sizeof(private_data->received_window));
    LOG_DEBUG(LOG_MODULE_NAME, "清空接收窗口");
    
    pthread_mutex_unlock(&private_data->mutex);
    LOG_DEBUG(LOG_MODULE_NAME, "释放互斥锁");
    
    LOG_INFO(LOG_MODULE_NAME, "序列号管理器重置成功");
    return PROTOCOL_SUCCESS;
}

/* ==================== 序列号查询函数实现 ==================== */

/**
 * @brief 获取当前发送序列号
 * @details 获取当前序列号管理器的发送序列号。该函数是线程安全的，
 *          使用互斥锁保护共享数据的访问。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * 
 * @return 当前发送序列号
 *         - 如果句柄为NULL，返回0
 *         - 否则返回当前发送序列号
 * 
 * @note 该函数是线程安全的
 * @see protocol_sequence_get_next_send
 * @see protocol_sequence_get_current_receive
 */
uint16_t protocol_sequence_get_current_send(protocol_sequence_handle_t handle) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取当前发送序列号，句柄: %p", handle);
    
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "序列号管理器句柄为空指针");
        return 0;
    }
    
    protocol_sequence_private_t* private_data = (protocol_sequence_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    uint16_t seq = private_data->current_send_seq;
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "当前发送序列号: %u", seq);
    return seq;
}

/**
 * @brief 获取当前接收序列号
 * @details 获取当前序列号管理器的接收序列号。该函数是线程安全的，
 *          使用互斥锁保护共享数据的访问。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * 
 * @return 当前接收序列号
 *         - 如果句柄为NULL，返回0
 *         - 否则返回当前接收序列号
 * 
 * @note 该函数是线程安全的
 * @see protocol_sequence_acknowledge_receive
 * @see protocol_sequence_get_current_send
 */
uint16_t protocol_sequence_get_current_receive(protocol_sequence_handle_t handle) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取当前接收序列号，句柄: %p", handle);
    
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "序列号管理器句柄为空指针");
        return 0;
    }
    
    protocol_sequence_private_t* private_data = (protocol_sequence_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    uint16_t seq = private_data->current_receive_seq;
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "当前接收序列号: %u", seq);
    return seq;
}

/**
 * @brief 获取未确认的发送序列号数量
 * @details 获取当前未确认的发送序列号数量。该函数是线程安全的，
 *          使用互斥锁保护共享数据的访问。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * 
 * @return 未确认的发送序列号数量
 *         - 如果句柄为NULL，返回0
 *         - 否则返回未确认数量
 * 
 * @note 该函数是线程安全的
 * @see protocol_sequence_get_next_send
 * @see protocol_sequence_acknowledge_send
 * @see protocol_sequence_can_send
 */
uint32_t protocol_sequence_get_unacknowledged_count(protocol_sequence_handle_t handle) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取未确认的发送序列号数量，句柄: %p", handle);
    
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "序列号管理器句柄为空指针");
        return 0;
    }
    
    protocol_sequence_private_t* private_data = (protocol_sequence_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    uint32_t count = private_data->unacknowledged_count;
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "未确认的发送序列号数量: %u", count);
    return count;
}

/**
 * @brief 检查是否可以发送
 * @details 检查是否可以发送新的序列号。该函数会比较当前未确认的序列号数量
 *          与最大未确认数量，判断是否还有发送窗口可用。该函数是线程安全的，
 *          使用互斥锁保护共享数据的访问。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * 
 * @return 是否可以发送
 *         - true: 可以发送（未确认数量未达到最大值）
 *         - false: 不能发送（未确认数量已达到最大值或句柄为NULL）
 * 
 * @note 该函数是线程安全的
 * @see protocol_sequence_get_next_send
 * @see protocol_sequence_get_unacknowledged_count
 */
bool protocol_sequence_can_send(protocol_sequence_handle_t handle) {
    LOG_DEBUG(LOG_MODULE_NAME, "检查是否可以发送，句柄: %p", handle);
    
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "序列号管理器句柄为空指针");
        return false;
    }
    
    protocol_sequence_private_t* private_data = (protocol_sequence_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    bool can_send = (private_data->unacknowledged_count < private_data->config.max_unacknowledged);
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "发送检查结果: %s (未确认数量: %u, 最大未确认: %u)", 
             can_send ? "可以发送" : "不能发送", 
             private_data->unacknowledged_count, 
             private_data->config.max_unacknowledged);
    return can_send;
}

/**
 * @brief 获取序列号统计信息
 * @details 获取序列号管理器的统计信息，包括各种操作的计数和状态。
 *          该函数会复制当前的统计信息到提供的缓冲区中，应用程序可以查看
 *          序列号管理器的运行状态。该函数是线程安全的，使用互斥锁保护。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param stats 统计信息输出缓冲区，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 获取成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 参数为空指针
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 获取的统计信息是当前时刻的快照
 * @see protocol_sequence_stats_t
 */
protocol_error_t protocol_sequence_get_stats(protocol_sequence_handle_t handle, 
                                           protocol_sequence_stats_t* stats) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取序列号统计信息，句柄: %p, 统计输出: %p", handle, stats);
    
    if (handle == NULL || stats == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "参数为空指针，句柄: %p, 统计输出: %p", handle, stats);
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_sequence_private_t* private_data = (protocol_sequence_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    memcpy(stats, &private_data->stats, sizeof(protocol_sequence_stats_t));
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "成功获取统计信息，总发送: %u, 总接收: %u, 重复检测: %u, 乱序检测: %u", 
             stats->total_sent, stats->total_received, stats->duplicates_detected, stats->out_of_order_detected);
    return PROTOCOL_SUCCESS;
}

/* ==================== 回调设置函数实现 ==================== */

/**
 * @brief 设置序列号错误回调函数
 * @details 设置序列号错误发生时的回调函数。当序列号管理器检测到错误
 *          （如重复序列号、乱序序列号、无效序列号等）时，系统会自动
 *          调用此回调函数通知应用程序。应用程序可以在此函数中处理各种
 *          序列号错误，实现自定义的错误处理逻辑。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param callback 错误处理回调函数指针，可以为NULL（表示取消回调）
 * @param user_data 用户数据指针，会传递给回调函数，可以为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 设置成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 如果callback为NULL，则取消错误回调
 * @warning 回调函数应该尽快返回，避免阻塞序列号管理器
 * @see protocol_sequence_error_callback_t
 * @see protocol_sequence_set_wrap_callback
 */
protocol_error_t protocol_sequence_set_error_callback(protocol_sequence_handle_t handle, 
                                                     protocol_sequence_error_callback_t callback, 
                                                     void* user_data) {
    LOG_DEBUG(LOG_MODULE_NAME, "设置序列号错误回调，句柄: %p, 回调: %p, 用户数据: %p", 
              handle, callback, user_data);
    
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "序列号管理器句柄为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_sequence_private_t* private_data = (protocol_sequence_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    private_data->error_callback = callback;
    private_data->error_user_data = user_data;
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "序列号错误回调设置成功");
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 设置序列号回绕回调函数
 * @details 设置序列号回绕发生时的回调函数。当序列号超过最大值发生回绕时，
 *          系统会自动调用此回调函数通知应用程序。应用程序可以在此函数中
 *          处理序列号回绕事件，实现自定义的回绕处理逻辑。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param callback 回绕处理回调函数指针，可以为NULL（表示取消回调）
 * @param user_data 用户数据指针，会传递给回调函数，可以为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 设置成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 如果callback为NULL，则取消回绕回调
 * @warning 回调函数应该尽快返回，避免阻塞序列号管理器
 * @see protocol_sequence_wrap_callback_t
 * @see protocol_sequence_set_error_callback
 */
protocol_error_t protocol_sequence_set_wrap_callback(protocol_sequence_handle_t handle, 
                                                    protocol_sequence_wrap_callback_t callback, 
                                                    void* user_data) {
    LOG_DEBUG(LOG_MODULE_NAME, "设置序列号回绕回调，句柄: %p, 回调: %p, 用户数据: %p", 
              handle, callback, user_data);
    
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "序列号管理器句柄为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_sequence_private_t* private_data = (protocol_sequence_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    private_data->wrap_callback = callback;
    private_data->wrap_user_data = user_data;
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "序列号回绕回调设置成功");
    return PROTOCOL_SUCCESS;
}

/* ==================== 配置管理函数实现 ==================== */

/**
 * @brief 更新序列号配置参数
 * @details 更新序列号管理器的配置参数，包括最大序列号、窗口大小、重试策略等。
 *          该函数会验证新配置的有效性，只有通过验证的配置才会被应用。
 *          配置更新是原子操作，使用互斥锁保护，确保配置的一致性。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param config 新的序列号配置参数，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 更新成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 参数为空指针
 *         - PROTOCOL_ERROR_INVALID_PARAM: 配置参数无效
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 配置更新会立即生效，影响后续的序列号操作
 * @warning 配置更新不会影响当前正在进行的序列号操作
 * @see protocol_sequence_config_t
 * @see protocol_sequence_validate_config
 * @see protocol_sequence_get_config
 */
protocol_error_t protocol_sequence_update_config(protocol_sequence_handle_t handle, 
                                                const protocol_sequence_config_t* config) {
    LOG_DEBUG(LOG_MODULE_NAME, "更新序列号配置，句柄: %p, 配置: %p", handle, config);
    
    if (handle == NULL || config == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "参数为空指针，句柄: %p, 配置: %p", handle, config);
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "验证新配置参数，最大序列号: %u, 窗口大小: %u, 最大未确认: %u", 
             config->max_sequence_number, config->window_size, config->max_unacknowledged);
    
    // 验证配置
    if (protocol_sequence_validate_config(config) != PROTOCOL_SUCCESS) {
        LOG_ERROR(LOG_MODULE_NAME, "序列号配置参数验证失败");
        return PROTOCOL_ERROR_INVALID_PARAM;
    }
    
    protocol_sequence_private_t* private_data = (protocol_sequence_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    memcpy(&private_data->config, config, sizeof(protocol_sequence_config_t));
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "序列号配置更新成功");
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 获取序列号配置参数
 * @details 获取序列号管理器的当前配置参数，包括最大序列号、窗口大小、重试策略等。
 *          该函数会复制当前的配置参数到提供的缓冲区中，应用程序可以查看
 *          当前的配置设置。配置获取是原子操作，使用互斥锁保护，确保数据的一致性。
 * 
 * @param handle 序列号管理器句柄，不能为NULL
 * @param config 配置参数输出缓冲区，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 获取成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 参数为空指针
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 获取的配置是当前生效的配置参数
 * @see protocol_sequence_config_t
 * @see protocol_sequence_update_config
 * @see protocol_sequence_validate_config
 */
protocol_error_t protocol_sequence_get_config(protocol_sequence_handle_t handle, 
                                            protocol_sequence_config_t* config) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取序列号配置，句柄: %p, 配置输出: %p", handle, config);
    
    if (handle == NULL || config == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "参数为空指针，句柄: %p, 配置输出: %p", handle, config);
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_sequence_private_t* private_data = (protocol_sequence_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    memcpy(config, &private_data->config, sizeof(protocol_sequence_config_t));
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "成功获取配置，最大序列号: %u, 窗口大小: %u, 最大未确认: %u", 
             config->max_sequence_number, config->window_size, config->max_unacknowledged);
    return PROTOCOL_SUCCESS;
}

/* ==================== 辅助函数实现 ==================== */

/**
 * @brief 获取序列号方向名称字符串
 * @details 将序列号方向枚举值转换为对应的字符串名称，用于日志记录和调试。
 *          该函数返回静态字符串数组中的对应项，返回的字符串指针在程序
 *          运行期间保持有效，不需要释放内存。
 * 
 * @param direction 序列号方向枚举值
 * 
 * @return 方向名称字符串
 *         - "SEND": 发送方向
 *         - "RECEIVE": 接收方向
 *         - "UNKNOWN": 未知方向（当direction值无效时）
 * 
 * @note 返回的字符串指针是静态的，不需要释放内存
 * @note 该函数是线程安全的，只读取静态数据
 * @see sequence_direction_t
 * @see protocol_sequence_get_state_name
 */
const char* protocol_sequence_get_direction_name(sequence_direction_t direction) {
    static const char* direction_names[] = {
        "SEND",
        "RECEIVE"
    };
    
    if (direction >= sizeof(direction_names) / sizeof(direction_names[0])) {
        return "UNKNOWN";
    }
    
    return direction_names[direction];
}

/**
 * @brief 获取序列号状态名称字符串
 * @details 将序列号状态枚举值转换为对应的字符串名称，用于日志记录和调试。
 *          该函数返回静态字符串数组中的对应项，返回的字符串指针在程序
 *          运行期间保持有效，不需要释放内存。
 * 
 * @param state 序列号状态枚举值
 * 
 * @return 状态名称字符串
 *         - "VALID": 有效状态
 *         - "INVALID": 无效状态
 *         - "DUPLICATE": 重复状态
 *         - "OUT_OF_ORDER": 乱序状态
 *         - "OVERFLOW": 溢出状态
 *         - "UNKNOWN": 未知状态（当state值无效时）
 * 
 * @note 返回的字符串指针是静态的，不需要释放内存
 * @note 该函数是线程安全的，只读取静态数据
 * @see sequence_state_t
 * @see protocol_sequence_get_direction_name
 */
const char* protocol_sequence_get_state_name(sequence_state_t state) {
    static const char* state_names[] = {
        "VALID",
        "INVALID",
        "DUPLICATE",
        "OUT_OF_ORDER",
        "OVERFLOW"
    };
    
    if (state >= sizeof(state_names) / sizeof(state_names[0])) {
        return "UNKNOWN";
    }
    
    return state_names[state];
}

/**
 * @brief 验证序列号配置参数的有效性
 * @details 验证序列号配置参数是否符合104协议的要求和系统限制。
 *          该函数会检查所有必要的配置参数，确保它们的值在有效范围内。
 *          验证包括最大序列号、窗口大小、最大未确认数量等关键参数的合理性检查。
 * 
 * @param config 待验证的序列号配置参数，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 配置验证通过
 *         - PROTOCOL_ERROR_NULL_POINTER: 配置参数为空指针
 *         - PROTOCOL_ERROR_INVALID_PARAM: 配置参数无效
 * 
 * @note 该函数是线程安全的，只读取配置数据
 * @note 验证规则：
 *       - 最大序列号必须大于0
 *       - 窗口大小必须大于0且不超过16
 *       - 最大未确认数量必须大于0且不超过16
 * @see protocol_sequence_config_t
 * @see protocol_sequence_update_config
 * @see protocol_sequence_get_config
 */
protocol_error_t protocol_sequence_validate_config(const protocol_sequence_config_t* config) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证序列号配置参数，配置: %p", config);
    
    if (config == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "序列号配置参数为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    LOG_DEBUG(LOG_MODULE_NAME, "检查配置参数，最大序列号: %u, 窗口大小: %u, 最大未确认: %u", 
              config->max_sequence_number, config->window_size, config->max_unacknowledged);
    
    if (config->max_sequence_number == 0 || config->window_size == 0 || config->max_unacknowledged == 0) {
        LOG_ERROR(LOG_MODULE_NAME, "配置参数不能为0，最大序列号: %u, 窗口大小: %u, 最大未确认: %u", 
                  config->max_sequence_number, config->window_size, config->max_unacknowledged);
        return PROTOCOL_ERROR_INVALID_PARAM;
    }
    
    if (config->window_size > 16 || config->max_unacknowledged > 16) {
        LOG_ERROR(LOG_MODULE_NAME, "窗口大小或最大未确认数量超过限制，窗口大小: %u, 最大未确认: %u", 
                  config->window_size, config->max_unacknowledged);
        return PROTOCOL_ERROR_INVALID_PARAM;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "序列号配置参数验证通过");
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 计算序列号差值
 * @details 计算两个序列号之间的差值，考虑序列号回绕情况。该函数会处理
 *          序列号超过最大值时的回绕情况，确保差值的计算结果是正确的。
 *          正值表示seq1大于seq2，负值表示seq1小于seq2。
 * 
 * @param seq1 序列号1
 * @param seq2 序列号2
 * @param max_seq 最大序列号
 * 
 * @return 序列号差值
 *         - 正值：seq1 > seq2
 *         - 负值：seq1 < seq2
 *         - 0：seq1 == seq2
 * 
 * @note 该函数是线程安全的，只进行数学计算
 * @note 函数会自动处理序列号回绕情况
 * @see protocol_sequence_is_in_window
 */
int32_t protocol_sequence_calculate_difference(uint16_t seq1, uint16_t seq2, uint16_t max_seq) {
    LOG_DEBUG(LOG_MODULE_NAME, "计算序列号差值，seq1: %u, seq2: %u, max_seq: %u", seq1, seq2, max_seq);
    
    int32_t diff = (int32_t)seq1 - (int32_t)seq2;
    
    // 处理回绕情况
    if (diff > max_seq / 2) {
        diff -= max_seq + 1;
        LOG_DEBUG(LOG_MODULE_NAME, "处理回绕情况，调整差值: %d", diff);
    } else if (diff < -(max_seq / 2)) {
        diff += max_seq + 1;
        LOG_DEBUG(LOG_MODULE_NAME, "处理回绕情况，调整差值: %d", diff);
    }
    
    LOG_DEBUG(LOG_MODULE_NAME, "序列号差值计算结果: %d", diff);
    return diff;
}

/**
 * @brief 检查序列号是否在窗口内
 * @details 检查序列号是否在指定的接收窗口内。该函数会计算序列号与窗口起始位置
 *          的差值，判断是否在窗口大小范围内。函数会自动处理序列号回绕情况。
 * 
 * @param sequence_number 要检查的序列号
 * @param window_start 窗口起始序列号
 * @param window_size 窗口大小
 * @param max_seq 最大序列号
 * 
 * @return 是否在窗口内
 *         - true: 序列号在窗口内
 *         - false: 序列号不在窗口内
 * 
 * @note 该函数是线程安全的，只进行数学计算
 * @note 函数会自动处理序列号回绕情况
 * @see protocol_sequence_calculate_difference
 * @see protocol_sequence_validate_receive
 */
bool protocol_sequence_is_in_window(uint16_t sequence_number, 
                                   uint16_t window_start, 
                                   uint16_t window_size, 
                                   uint16_t max_seq) {
    LOG_DEBUG(LOG_MODULE_NAME, "检查序列号是否在窗口内，序列号: %u, 窗口起始: %u, 窗口大小: %u, 最大序列号: %u", 
              sequence_number, window_start, window_size, max_seq);
    
    int32_t diff = protocol_sequence_calculate_difference(sequence_number, window_start, max_seq);
    bool in_window = (diff >= 0 && diff < window_size);
    
    LOG_DEBUG(LOG_MODULE_NAME, "窗口检查结果: %s (差值: %d)", in_window ? "在窗口内" : "不在窗口内", diff);
    return in_window;
}
